
\section{Specifying the Plotted Range}

\subsection{Configuration of Limits Ranges}

\begin{pgfplotsxykeylist}{%
    \x min=\marg{coord},
    \x max=\marg{coord},
    min=\marg{coord},
    max=\marg{coord}%
}
    These options allow to define the axis limits, i.e.\@ the lower left and
    the upper right corner. Everything outside of the axis limits will be
    clipped away.


    \paragraph{Attention:}

    these values (and other related keys in this section) merely affect how
    \PGFPlots{} determines the axis' range. The values are \emph{unrelated} to
    function sampling. Please refer to |domain| in order to define the sampling
    range for plot expressions. It is valid to sample a larger or smaller range
    than the displayed portion of the axis. Use |xmin| and its friends to
    specify which portion of the axis is to be displayed.

    Each of these keys is optional, and missing limits will be determined
    automatically from input data. Here, the |min| and |max| keys set limits
    for $x$, $y$ and $z$ to the same \meta{coord}.

    If $x$ limits have been specified explicitly and $y$ limits are computed
    automatically, the automatic computation of $y$ limits will only considers
    points which fall into the specified $x$-range (and vice versa). The same
    holds true if, for example, only |xmin| has been provided explicitly: in
    that case, |xmax| will be updated only for points for which $x \ge
    \;$|xmin| holds. This feature can be disabled using |clip limits=false|.

    Axis limits can be increased automatically using the |enlargelimits|
    option.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    title=Auto Limits,
]
    \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    title={\texttt{xmin=0}},
    xmin=0,
]
    \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    title={\texttt{ymax=10}},
    ymax=10,
]
    \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that even if you provide |ymax=10|, data points with $y>10$ will still
    be visualized -- producing a line which leaves the plotted range.

    See also the |restrict x to domain| and |restrict x to domain*| keys --
    they allow to discard or clip input coordinates which are outside of some
    domain, respectively.

    During the visualization phase, i.e.\@ during |\end{axis}|, these keys will
    be set to the final axis limits. You can access the values by means of
    |\pgfkeysvalueof{/pgfplots/xmin}|, for example:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
 % Show (automatically) computed limits:
 title={
  Axis limits are
  $
 [\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/xmin}}
 :\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/xmax}}
 ]  \times
 [\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/ymin}}
 :\pgfmathprintnumber{\pgfkeysvalueof{/pgfplots/ymax}}
 ]$ },
]
    \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
        \label{page:access:limits}
    This access is possible inside of any axis description (like |xlabel|,
    |title|, |legend entries|, etc.) or any annotation (i.e.\@ inside of
    |\node|, |\draw| or |\path| and coordinates in |(|\meta{x}|,|\meta{y}|)|),
    but not inside of |\addplot| (limits may not be complete at this stage).
\end{pgfplotsxykeylist}

\begin{pgfplotsxykey}{\x mode=\mchoice{normal,linear,log} (initially normal)}
    Allows to choose between linear (= normal) or logarithmic axis scaling or
    log plots for each $x,y,z$-combination.

    Logarithmic plots use the current setting of |log basis x| and its variants
    to determine the basis (default is $e$).
    % FIXME : replicated in pgfplots.reference.scaling.tex
\end{pgfplotsxykey}

\begin{pgfplotsxykey}{\x\ dir=\mchoice{normal,reverse} (initially normal)}
\label{key:pgfplots:xydir}%
\pgfkeys{/pdflinks/search key prefixes in/.add={/pgfplots/,}{}}
    Allows to reverse axis directions such that values are given in decreasing
    order.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    xlabel=$x$ \emph{decreasing} $\to$,
    x dir=reverse,
]
    \addplot {x + rand*0.3};
\end{axis}
\end{tikzpicture}
\end{codeexample}

\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    ylabel=$y$ \emph{decreasing} $\to$,
    y dir=reverse,
]
    \addplot {x^2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that axis descriptions and relative positioning macros will stay at
    the same place as they would for non-reversed axes.
    %
\begin{codeexample}[]
\begin{tikzpicture}
    \begin{axis}[
        ylabel=$y$ \emph{decreasing} $\to$,
        xlabel=$x$ normal,
        title=reversed axis,
        y dir=reverse,
        colorbar,
        colorbar style={y dir=reverse},
    ]
        \addplot+ [mesh,scatter] {x^15};
    \end{axis}
\end{tikzpicture}
\end{codeexample}

    Note that |colorbar|s won't be reversed automatically, you will have to
    reverse the sequence of color bars manually in case this is required as in
    the preceding example.
\end{pgfplotsxykey}

\begin{pgfplotsxykeylist}{clip \x limits=\mchoice{true,false} (initially true),clip limits=\mchoice{true,false}}
    Configures what to do if some, but not all axis limits have been specified
    explicitly. In case |clip limits=true|, the automatic limit computation
    will \emph{only} consider points which do not contradict the explicitly set
    limits.

    The effect of |clip xlimits=true| is that if the $x$-coordinate of some
    point $(x,y)$ falls outside of the limits specified by |xmin| and |xmax|,
    neither $x$ nor $y$ will contribute to the automatically computed axis
    limits. The key |clip limits| is an alias which sets all the other options
    at once.

    This option has nothing to do with path clipping, it only affects how the
    axis limits are computed.
\end{pgfplotsxykeylist}

\begin{pgfplotsxykeylist}{%
    enlarge \x\ limits=\mchoice{%
        auto,
        true,false,
        upper,lower,
        \meta{val},value=\meta{val},
        abs value=\meta{val},\\ abs=\meta{val},
        rel=\meta{val}%
    } (initially auto),
    enlargelimits=\meta{common value}%
}
    Enlarges the axis size for one axis (or all of them for |enlargelimits|)
    somewhat if enabled.

    You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values
    of your data and |enlarge x limits| will enlarge the canvas such that the
    axis doesn't touch the plots.

    The value \declaretext{true} enlarges the lower and upper limit.

    The value \declaretext{false} uses tight axis limits as specified by the
    user (or read from input coordinates).

    The value \declaretext{auto} will enlarge limits only for axis for which
    axis limits have been determined automatically. For three-dimensional
    figures, the \declaretext{auto} mechanism applies only for the $z$-axis.
    The $x$- and $y$-axis won't be enlarged.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    small,
]
    \addplot {5 * x^3 - x^2 + 4*x -2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

     Specifying a number \declaretext{val}ue like `|enlarge x limits=0.2|' will
     enlarge lower and upper axis limit relatively. The following example adds
     $20\%$ of the axis limits on both sides:
     %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    small,
    enlarge x limits=0.2,
]
    \addplot {5 * x^3 - x^2 + 4*x -2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent The choice \declaretext{rel=}\marg{value} is the same as
    |true,value=|\marg{value}, i.e.\@ it activates relative enlargement for
    both |upper| and |lower| limit.

    The value \declaretext{upper} enlarges only the upper axis limit while
    \declaretext{lower} enlarges only the lower axis limit. In this case, the
    amount added to the respective limit can be specified using the
    \declaretext{value=}\marg{val} key. It can be combined with any of the
    other possible values. For example,

        |\pgfplotsset{enlarge x limits={value=0.2,upper}}|

    will enlarge (only) the upper axis limit by $20\%$ of the axis range.
    Another example is

        |\pgfplotsset{enlarge x limits={value=0.2,auto}}|

    which changes the default threshold of the \declaretext{auto} value to
    $20\%$.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    small,
    minor x tick num=1,
    enlarge x limits={rel=0.5,upper},
]
    \addplot {5 * x^3 - x^2 + 4*x -2};
\end{axis}
\end{tikzpicture}
\end{codeexample}

     While |value| uses relative thresholds, \declaretext{abs value} accepts
     absolute values: it adds an absolute value to the selected axis. The
     choice \declaretext{abs=}\marg{value} is the same as
     |true,abs value=|\marg{value}, i.e.\@ it adds an absolute value to both
     |upper| and |lower| limit:
     %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[
    small,
    minor x tick num=1,
    enlarge x limits={abs=3},
]
    \addplot {5 * x^3 - x^2 + 4*x -2};
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent Here, we enlarged by $3$ units of the $x$-axis. Note that you can
    also specify \emph{dimensions} like |1cm|:
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{axis}[small,minor x tick num=1,
    enlarge x limits={abs=1cm},
]
    \addplot {5 * x^3 - x^2 + 4*x -2}
        coordinate [pos=0] (first)
        coordinate [pos=1] (last);

    \draw [red,->] (first) -- ++(-1cm,0pt);
    \draw [red,->] (last)  -- ++( 1cm,0pt);
\end{axis}
\end{tikzpicture}
\end{codeexample}
    %
    \noindent Technically, the use of absolute dimensions is a little bit
    different. For example, it allows to enlarge by more than |width| which is
    impossible for all other choices. \PGFPlots{} will try to fulfill both the
    provided |width|/|height| and the absolute axis enlargements. If it fails
    to do so, it will give up on |width|/|height| constraints and print a
    warning message to your logfile. See also the key
    |enlargelimits respects figure size|.
    \index{Errors!enlargelimits respects figure size=true: could not respect the prescribed width/height}


    \paragraph{Attention:}

    |abs value| is applied \emph{multiplicatively} for logarithmic axes! That
    means |abs value=10| for a logarithmic axis adds $\log 10$ to upper and/or
    lower axis limits.
    %
\begin{codeexample}[]
\begin{tikzpicture}
\begin{loglogaxis}[
    small,
    enlarge x limits={abs=11},
]
    \addplot+ [domain=1:100000] {x^-2};
\end{loglogaxis}
\end{tikzpicture}
\end{codeexample}

    Note that |enlargelimits| is applied before any changes to axis limits are
    considered as part of |scale mode|: |enlargelimits| will always be applied.
    Afterwards, the choice |scale mode=scale uniformly| will enlarge limits
    once more in order to satisfy all scaling constraints. The two limit
    enlargements are independent of each other, i.e.\@ even if you say
    |enlargelimits=false|, |scale mode| will still increase axis limits if this
    seems to be necessary. An exception for this rule is enlarge-by-dimension,
    i.e.\@ something like |abs=1cm| (see |enlargelimits respects figure size|
    for this case). See |scale mode| (especially |scale mode=units only|) and
    |unit rescale keep size| for detail on how to disable limit enlargement
    caused by |scale mode|.
\end{pgfplotsxykeylist}

\begin{pgfplotskey}{enlargelimits respects figure size=\mchoice{true,false} (initially true)}
    A key which is \emph{only} used for something like
    |enlarge x limits={abs=1cm}|, i.e.\@ for enlarge-by-dimension. It controls
    if \PGFPlots{} will try to respect |width|/|height|. You should probably
    always leave it as its default unless you run into problems.

    If \PGFPlots{} fails to respect the figure size, it will print a warning
    message of sorts ``enlargelimits respects figure size=true: could not
    respect the prescribed width/height'' to your logfile.
    \index{Errors!enlargelimits respects figure size=true: could not respect the prescribed width/height}
\end{pgfplotskey}

\begin{pgfplotsxykeylist}{%
    log origin \x=\mchoice{0,infty} (initially infty),
    log origin=\mchoice{0,infty} (initially infty)%
}
    Allows to choose which coordinate is the logical ``origin'' of a
    logarithmic plot (either for a particular axis or for all of them).

    The choice |log origin=infty| is probably useful for stacked plots: it
    defines the ``origin'' in log coordinates to be $-\infty$. To be compatibly
    with older versions, this is the default. Note that $-\infty$ is clipped to
    be the lowest displayed value on the axis in question.

    The choice |log origin=0| defines the logarithmic origin to be the natural
    choice $\log(1)=0$. This is particularly useful for |ycomb| plots.
\end{pgfplotsxykeylist}

\begin{pgfplotskey}{update limits=\mchoice{true,false} (initially true)}
    Can be used to interrupt updates of the data limits (for example, for
    single |\addplot| commands).

    This has the same effect as
    |\pgfplotsinterruptdatabb| ... |\endpgfplotsinterruptdatabb|.
\end{pgfplotskey}

\begin{environment}{{pgfplotsinterruptdatabb}}
\index{Bounding Box Control!Disable \protect\emph{data} bounding box modifications}
    Everything in \meta{environment contents} will not contribute to the data
    bounding box.

    The same effect can be achieved with |update limits=false| inside curly
    braces.
\end{environment}


\subsection{Accessing Computed Limit Ranges}

This section is for those who want or need to access the computed limits
programmatically. It lists how to access computed values.

\begin{pgfplotsxykeylist}{\x min,\x max}
    These values are not only the \emph{input}: after the survey phase, their
    values will be overwritten with the resulting computed values. These may
    differ according to |enlargelimits| or |scale mode|.

    If you need to access them, you can write |\pgfkeysvalueof{/pgfplots/xmin}|
    somewhere in your code.
\end{pgfplotsxykeylist}

%--------------------------------------------------
% \begin{pgfplotsxykeylist}{axis/zero/\x}
%     These values will be populated with the ``zero'' values of the respective axis. This zero value can differ from `$0$' due to either the configuration or programmatical usefulness:
%
%     \begin{itemize}
%         \item if the axis is linear and $0$ is part of the displayed limits, the key will expand to~$0$.
%         \item if the axis is linear but $0$ is outside of the displayed limits, the key will expand to the nearest point inside of the axis limits.
%         \item if the axis is logarithmic, the value will be set according to the |log origin| key and will be clipped to the displayed limits.
%     \end{itemize}
%
%     These keys are a property of the axis; they are unrelated to ``zero levels'' in the context of stacked plots.
% \end{pgfplotsxykeylist}
%--------------------------------------------------
